Greengrass Reference Implementation
The Greengrass Reference Implementation is a fully functional, deployable AWS IoT Greengrass gateway running on CompuLab IOT-GATE-iMX8 hardware. It scans for nearby Milwaukee Tool BLE advertisements, collects GNSS/LTE location data, and publishes to AWS IoT Core over cellular. In doing so it exercises the full Remote Comms contract on actual hardware.
It is a baseline for building and rapidly validating the cloud platform independent of other workstreams. It is a real connected device the software team can control end to end, not a simulation.
This gateway is a long-lived test harness for the platform. Edge Mesh is a separate, temporary and experimental proof-of-concept built on top of it.
Why it exists
| # | Value | What it gives us |
|---|---|---|
| 1 | Validate cloud infrastructure, device-agnostic | The platform and its services should not be coupled to a single product's firmware implementation decisions. A real connected Greengrass implementation lets us exercise CPP services, shadow sync, jobs, and OTA independently of hardware or firmware implementation details. |
| 2 | De-risk future bridge platforms on Linux & Greengrass | If future bridge hardware moves to a Linux-based OS, this work becomes a great starting point and/or reference architecture. |
| 3 | Test with real hardware, not simulated behavior | The iot-testing CLI app approximates device behavior in software. The Greengrass gateway runs on actual iMX8 hardware, which surfaces integration edge cases that simulation can't expose. |
| 4 | Lower the bar for platform onboarding & troubleshooting | A deployable, documented gateway lets any engineer explore the full Digital IoT platform stack without waiting for production hardware access or firmware expertise. |
| 5 | Debug anomalies without a firmware build cycle | Greengrass components are independently deployable over-the-air. We can isolate issues, change behavior, and iterate on configs in minutes without relying on a hardware build. |
The reference implementation currently targets the dev environment in us-east-1. Staging and production configurations exist in the repo but are not yet active deployment targets, so treat it as a dev/test harness rather than a production device.
What runs on it
Various Greengrass components run on the core and coordinate over local IPC pub/sub:
- cert-manager: certificate lifecycle (manufacturing bootstrap, MQTT fleet provisioning, operational cert rotation).
- location-collector: reads GNSS and LTE cell data from the modem, publishes location fixes to the IPC bus.
- ble-scanner: scans nearby Milwaukee Tool BLE advertisements, writes scan session files to disk.
- asset-publisher: publishes BLE scan sessions to IoT Core.
- device-reporter: writes the
identityandstatusdevice shadows once at boot. - health-portal: on-device web dashboard for health checks and diagnostics.
See the iot-edge repository for the full list of current components.
Explore this section
New here? Start with Getting Started to stand up a gateway, then use the Health Portal to watch it run. To understand the internals, read Architecture and Data Path.
- Getting Started: bring up a gateway, verify it's healthy, and troubleshoot the common first problems.
- Health Portal: the on-device dashboard for observing and operating the gateway.
- Architecture: how the various components fit together, covering the component map, the local IPC bus, startup ordering, and identity/certificates.
- Data Path: what actually flows through the box, namely the BLE-scan-to-cloud pipeline and the device-shadow writes.
For the operational source of truth (recipes, deploy commands, and the full setup procedure), see the iot-edge repository README.
Relationship to the Remote Comms contract
The reference implementation is a concrete device that implements the device-agnostic behaviors the rest of this section specifies:
- Device Provisioning: the two-phase certificate model, run by
cert-manager. - Device Shadows: device state over direct MQTT, written by
device-reporterandasset-publisher. - Asset Scans: the RP2 payloads published by
asset-publisher. - OTA: firmware and component update delivery via AWS IoT Jobs.
Where the code lives
iot-edgerepo: runtime, components, IPC flow, provisioning, and deployment.
Edge Mesh (experimental)
Edge Mesh is a highly experimental proof-of-concept built on top of this reference implementation. It links the iMX8 core with a fleet of Raspberry Pi mesh-nodes over an isolated WiFi mesh to extend BLE-scan coverage and relay remote tool control. It was built as a learning exercise and will likely be removed from the codebase in the future; the reference implementation of the Greengrass Core Device itself is here to stay.